Convert all DID Method entries to JSON files. #353

msporny · 2021-11-01T16:22:09Z

This PR is the first in a series to convert all DID Method entries to JSON files that contain links to information about the DID Method. This PR is purely additive, it only adds files that are not used at the moment, a future PR will use these files to auto-generate the table(s) of DID Methods.

This PR also removes the "PROVISIONAL" status marker, keeping the "DEPRECATED" and "WITHDRAWN" markers.

Preview | Diff

methods/key.json

TallTed

One tweak for internal consistency. Otherwise, appears to do what it says on the tin.

OR13 · 2021-11-01T17:23:42Z

methods/3.json

+  "description": "",
+  "status": "",
+  "registry": "Ceramic Network",
+  "contact": "<a href=\"mailto:oed@3box.io\">Joel Thorstensson</a>",


prefer json to not include XSS vectors.

At present, we allow HTML markup in all entries (this is nothing new, we've operated like this for a while). We have a review process that's supposed to catch bad things like script injection from happening. If something bad does get through, it runs in the browser context anyway -- that is, the security model is the same as browsing to any website.

I think we're good here, at least for the time being, and we can always add a post-processing step that only allows a subset of HTML tags (but I expect that to be pretty heavy handed). Or we require contact information to be an email address (which means that almost every entry is not going to have that information).

At present, we allow HTML markup in all entries (this is nothing new, we've operated like this for a while).

This PR is the first time we have added JSON files which contain html markup to the registry, and we should not start by encouraging dom based xss via respec.

is contact always an email? why not call it "email" and make it an email?

is contact always an email? why not call it "email" and make it an email?

No, it isn't. Sometimes it's an email. Sometimes it's a website. Sometimes it's just a name. Sometimes it's just the name of a company. So, what of those options are we going to force people to do (because they all seem like valid options, IMHO).

ok thats fair, I think its easier to express that as optional fields.... Like this:

title: DID Method Registry Entry description: This schema defines the shape of did method registrations in the did spec registries type: object required: - status - name - specification properties: status: description: "The status of the entry in the registry". type: string enum: ["accepted", "withdrawn", "deprecated"] name: description: https://www.w3.org/TR/did-core/#dfn-did-methods type: string maxLength: 256 example: "did:example" description: description: "A description of the entry in the registry.". type: string maxLength: 256 example: "did:example is reserved for examples." specification: description: "An active URL that resolves to a human readable did method specification". type: string maxLength: 1024 example: "https://example.com/example-did-method-spec" contactName: description: "An optional contact point name". type: string maxLength: 256 example: "Example Corp. Support" contactEmail: description: "An optional contact point email". type: string maxLength: 256 example: "support@example.com" contactWebsite: description: "An optional contact point website". type: string maxLength: 1024 example: "example.com" verifiableDataRegistry: description: https://www.w3.org/TR/did-core/#dfn-verifiable-data-registry type: string maxLength: 256 example: "Bitcoin / Ethereum + IPFS / Hyperledger" rubricEvaluation: description: "An active URL that resolves to a human readable did method evaluation". type: string maxLength: 1024 example: "" additionalProperties: false

additionalProperties: false <- this is key.

Ok, good, thanks for being specific.

I'm reworking the schema you have above into the conversion script (I don't think we need maxLength, but shrug -- if you want it go ahead and put it in there). Bonus points if you want to work the JSON Schema above into a Github merge test for all PRs in the methods/ directory.

I implemented the schema above in the latest PR commits. The only change I didn't take was the "accepted" language... I chose to use "registered" instead.

We may not even want to have "registered", since it's obvious that it's registered if it's in the DID Spec Registries. So, it's either blank or "withdrawn"/"deprecated". We may even want to collapse both of those entries into "deprecated".

OR13

@msporny thanks for this PR.

I have a few concerns, listing them in priority order here:

1. Preventing Double Work.

If we accept this PR, it should be complete with instructions for new registrations, and functional, in that there is only a single entry related to existing registry entries in the repo after merging.

Otherwise, we will have folks adding to the "old registry" making more work for maintainers of the "new registry"...

2. Documenting All JSON Members

There should be a description of each JSON member, and its requirements.

Allowed characters, min max length, required or optional, etc...

3. Document New Registration Process

Instructions should be provided so we can adopt the new process completely, and close all open PRs related to the old process.

4. Can we do this via code first?

is there a script that is used to generate these files?

I prefer to review a script first, not a bunch of generated files... easier to adjust the output as desired.

This would make it much easier to review the intention behind the PR.

Next Steps

I can help document the proposed JSON members and help on a script to generate these files.

Can we remove the new files being added and instead add the script, json requirements and new registration requirements, and then generate the data at the end, once we have agreed to the new structure?

OR13 · 2021-11-01T18:50:26Z

Here are some constraints on the registry members and their descriptions: #353 (comment)

msporny · 2021-11-01T19:17:56Z

Can we do this via code first?

Code is here:

https://gist.github.com/msporny/1fdcb0b98050b849614e1c9fd6a341de

Preventing Double Work.
If we accept this PR, it should be complete with instructions for new registrations, and functional, in that there is only a single entry related to existing registry entries in the repo after merging.
Otherwise, we will have folks adding to the "old registry" making more work for maintainers of the "new registry"...

No, for two reasons:

The PR is meant to be coupled with other PRs for instructions for new registrations (feel free to work on that PR, please).
There is a conversion script, so anything merged in the interim is easy to convert out of the main index.html until we replace it with the ReSpec autogenerator (which I plan to get done soon-ish), so I expect that this won't be a huge problem in practice.

There is a plan to do what you want, but -1 to bundling them all into a single PR. All this PR does is the conversion. A separate PR will do the instructions for new registrations. Yet another separate PR will do the ReSpec auto-generation of the DID Method table. That's the plan so that we can have PRs that do one thing so it's easier to collaborate and merge on each subunit of work.

Documenting All JSON Members
There should be a description of each JSON member, and its requirements.

Please document this and put it into a PR in a way that is acceptable to you so that we can review.

Document New Registration Process
Instructions should be provided so we can adopt the new process completely, and close all open PRs related to the old process.

Same as above... separate PR, please.

If you choose to work on the two separate PRs above, please let me know so we don't duplicate work.

OR13 · 2021-11-01T20:43:50Z

@msporny based on your feedback, let me take a stab at a separate PR, consider the ball in my court.

OR13 · 2021-11-02T04:10:32Z

Lets close this PR, and continue to discussion on: #356

This PR adds a too many generated files, and does not meet the acceptance criteria for a transition of registry format I listed above.

OR13 · 2021-11-04T17:17:40Z

@msporny can we close this? your PR #357 seems a better starting place.

msporny · 2021-11-04T18:34:41Z

@msporny can we close this? your PR #357 seems a better starting place.

PR #357 is based on top of this one. :)

What we can do here is eliminate all the new fields? I think that's what you were asking for on the call today? I'm pretty sure I heard @jricher say that he hated the description field with the burning passion of a thousand suns, so I could eliminate that one as well as the others... but we might want to keep them around to see how much people like/hate them.

I'm fine w/ clawing this entire PR back to "just the information we have today".

mprorock · 2021-11-04T21:49:49Z

I would like to also see a an optional link to an example in addition to the optional link to to the rubric eval in the schema for the json entries

msporny · 2021-11-06T18:21:18Z

I would like to also see a an optional link to an example in addition to the optional link to to the rubric eval in the schema for the json entries

Can we do this in another PR that just focuses on "fields we want to add"?

msporny · 2021-11-06T18:25:08Z

Based on feedback from the last telecon, I have:

Updated this PR to only cover converting the current HTML-based entry method that we have to a JSON-based entry method.
Removed any new proposed fields, which will be handled in a future PR (that proposes the new field(s) and modifies all JSON files to include the new field(s)).
Temporarily included the tooling to do the conversion, which will be removed before merging to main.
Renamed "provisional" to "registered".

I believe that removes every controversy in this PR that was identified during the last telecon. I believe this PR is now ready for review and merge.

msporny · 2021-11-14T18:53:53Z

Editorial, multiple reviews, changes requested and made, no remaining objections, merging.

msporny requested a review from OR13 as a code owner November 1, 2021 16:22

msporny requested review from mprorock, brentzundel, TallTed and talltree November 1, 2021 16:22

msporny force-pushed the msporny-did-json branch from be8631c to b4659e9 Compare November 1, 2021 16:25

TallTed reviewed Nov 1, 2021

View reviewed changes

methods/key.json Outdated Show resolved Hide resolved

TallTed approved these changes Nov 1, 2021

View reviewed changes

OR13 reviewed Nov 1, 2021

View reviewed changes

OR13 requested changes Nov 1, 2021

View reviewed changes

OR13 mentioned this pull request Nov 1, 2021

Remove PROVISIONAL status from all DID method registrations #351

Merged

msporny force-pushed the msporny-did-json branch 3 times, most recently from a73f65f to 1fd95c2 Compare November 1, 2021 19:59

msporny force-pushed the msporny-did-json branch from 1fd95c2 to 9064109 Compare November 4, 2021 14:58

msporny marked this pull request as draft November 4, 2021 15:52

msporny force-pushed the msporny-did-json branch 2 times, most recently from 92666fb to 3598609 Compare November 6, 2021 18:19

msporny marked this pull request as ready for review November 6, 2021 18:25

msporny requested a review from OR13 November 6, 2021 18:25

msporny force-pushed the msporny-did-json branch from 3598609 to 5b66f18 Compare November 6, 2021 19:11

msporny added 24 commits November 14, 2021 13:52

Convert did:stack to JSON entry.

8d90d22

Convert did:tangle to JSON entry.

495b4cb

Convert did:tls to JSON entry.

0d5a460

Convert did:trust to JSON entry.

189642c

Convert did:trustbloc to JSON entry.

6e3a4ae

Convert did:trx to JSON entry.

9dc4848

Convert did:ttm to JSON entry.

c9c432a

Convert did:twit to JSON entry.

539edcb

Convert did:tyron to JSON entry.

c163d7f

Convert did:tys to JSON entry.

4bb7b74

Convert did:tz to JSON entry.

6e14b01

Convert did:unik to JSON entry.

8c94cf8

Convert did:unisot to JSON entry.

483d9ea

Convert did:uns to JSON entry.

003874f

Convert did:uport to JSON entry.

e7732fe

Convert did:v1 to JSON entry.

0a37521

Convert did:vaa to JSON entry.

66e8746

Convert did:vaultie to JSON entry.

6ff565f

Convert did:vid to JSON entry.

9fa0a26

Convert did:vivid to JSON entry.

bfb46e7

Convert did:vvo to JSON entry.

3442e6f

Convert did:web to JSON entry.

67e045e

Convert did:wlk to JSON entry.

1657a62

Convert did:work to JSON entry.

7a3b0e8

msporny force-pushed the msporny-did-json branch from 26355ee to 7a3b0e8 Compare November 14, 2021 18:52

msporny merged commit f1e3187 into main Nov 14, 2021

msporny deleted the msporny-did-json branch November 14, 2021 18:54

This was referenced Nov 16, 2021

Restore contact names for did:erc725 #368

Merged

Restore contact names for did:erc725 (again) #373

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Convert all DID Method entries to JSON files. #353

Convert all DID Method entries to JSON files. #353

msporny commented Nov 1, 2021 •

edited by pr-preview bot

TallTed left a comment

OR13 Nov 1, 2021

OR13 Nov 1, 2021

msporny Nov 1, 2021

OR13 Nov 1, 2021

msporny Nov 1, 2021

OR13 Nov 1, 2021 •

edited

OR13 Nov 1, 2021

msporny Nov 1, 2021 •

edited

msporny Nov 1, 2021

OR13 left a comment

OR13 commented Nov 1, 2021

msporny commented Nov 1, 2021 •

edited

OR13 commented Nov 1, 2021

OR13 commented Nov 2, 2021

OR13 commented Nov 4, 2021

msporny commented Nov 4, 2021 •

edited

mprorock commented Nov 4, 2021

msporny commented Nov 6, 2021

msporny commented Nov 6, 2021

msporny commented Nov 14, 2021

Convert all DID Method entries to JSON files. #353

Convert all DID Method entries to JSON files. #353

Conversation

msporny commented Nov 1, 2021 • edited by pr-preview bot

TallTed left a comment

Choose a reason for hiding this comment

OR13 Nov 1, 2021

Choose a reason for hiding this comment

OR13 Nov 1, 2021

Choose a reason for hiding this comment

msporny Nov 1, 2021

Choose a reason for hiding this comment

OR13 Nov 1, 2021

Choose a reason for hiding this comment

msporny Nov 1, 2021

Choose a reason for hiding this comment

OR13 Nov 1, 2021 • edited

Choose a reason for hiding this comment

OR13 Nov 1, 2021

Choose a reason for hiding this comment

msporny Nov 1, 2021 • edited

Choose a reason for hiding this comment

msporny Nov 1, 2021

Choose a reason for hiding this comment

OR13 left a comment

Choose a reason for hiding this comment

1. Preventing Double Work.

2. Documenting All JSON Members

3. Document New Registration Process

4. Can we do this via code first?

Next Steps

OR13 commented Nov 1, 2021

msporny commented Nov 1, 2021 • edited

OR13 commented Nov 1, 2021

OR13 commented Nov 2, 2021

OR13 commented Nov 4, 2021

msporny commented Nov 4, 2021 • edited

mprorock commented Nov 4, 2021

msporny commented Nov 6, 2021

msporny commented Nov 6, 2021

msporny commented Nov 14, 2021

msporny commented Nov 1, 2021 •

edited by pr-preview bot

OR13 Nov 1, 2021 •

edited

msporny Nov 1, 2021 •

edited

msporny commented Nov 1, 2021 •

edited

msporny commented Nov 4, 2021 •

edited